//
//  TMMacro.h
//  Textmaster
//
//  Created by Anshu Chimala on 1/1/10.
//  Copyright 2010 MediaLocal LLC. All rights reserved.
//

#import <Cocoa/Cocoa.h>

@protocol TMMacroDelegate;

@protocol TMMacro
@required
- (NSString *)title;			// return the macro's title.			Example: "Capitalize Text"
- (NSString *)author;			// return the macro's author.			Example: "Anshu Chimala"
- (NSString *)description;		// return the macro's description.		Example: "Capitalizes every character of the text."

// This is the body of your macro. You must do something with the text here.
// You may assume your delegate has been set to a class that conforms to the
// TMMacroDelegate protocol.
// If this is a very simple macro (for example, the capitalization macro), you
// might do something like:
//		text = [text uppercaseString];
//		[self.delegate macro:self didProcessTextWithResult:text];
// On the other hand, if you need to do something time consuming like HTTP
// requests or whatever, do that first and then call the delegate method.
- (void)processText:(NSString *)text;

- (NSString *)beforeText;		// return the sample text. For example, "Lorem ipsum..."
// return nil if you don't want sample text.

- (NSString *)afterText;		// return the product of running your macro on the example
// return nil if you don't want sample text.

// Your delegate. This will be given to you.
// You should call the appropriate methods at the right time.
// See the notes below for details.
// NOTE: Your macro class should have a variable to store the delegate.
//		 (See the sample code online)
@property (nonatomic, retain) id<TMMacroDelegate> delegate;

@optional

// If your macro is time-consuming and you need to display the progress
// indicator, you should implement this method and return a progress
// message.
- (NSString *)progressMessage;

@end

#pragma mark -
#pragma mark TMMacroDelegate

// Every macro will receive an instance of a class implementing this protocol
// as its delegate. It is your job as the macro's programmer to send these
// messages to the delegate at the appropriate time.
@protocol TMMacroDelegate
@required

// Call this method when your macro is done processing.
- (void)macro:(id<TMMacro>)macro didProcessTextWithResult:(NSString *)result;

// Call this method if your macro failed for some reason.
// This will cause Textmaster to report errorMessage as it
// is given, so make sure it is human readable.
- (void)macro:(id<TMMacro>)macro didFailWithErrorMessage:(NSString *)errorMessage;

// This defaults to NO.
// Set this to YES if your macro is doing something that will
// take a little bit of time (for example, making an HTTP
// connection).
// This will show an indeterminate progress indicator that
// lets the user know something is going on.
// NOTE: You are expected to set this to YES when you start
// and back to NO when you're done.
@property (nonatomic, assign) BOOL showActivityIndicator;

// This defaults to YES.
// Set this to NO if your macro does something that would be time
// consuming or annoying to update the sample display as the user
// edits the "Before" text view.
// (this'll make the "Before" box uneditable).
//@property (nonatomic, assign) BOOL userCanEditSampleText;
// NOTE: This feature may be implemented in the future but shouldn't be used now.

// This defaults to YES
// Set this to NO if you don't want Textmaster to automatically
// paste the result of your macro after you've executed it.
// (For example, if your macro doesn't actually transform the
// text but perhaps launches a URL or something)
@property (nonatomic, assign) BOOL shouldPasteAfterwards;

@end
